星辰 Workflow Open API 接口文档

本协议用于描述如何调用星辰 Agent 开发平台 Workflow OpenAPI，您需要先在星辰大模型应用平台完成工作流的创建，调试通过并发布后，即可调用此服务。

一、执行工作流

1. 基础信息

1.1 接口说明

1.2 接口Demo

接口Demo随后提供。

1.3 接口要求

接口类型: 流式http(s)

接口鉴权: Bearer鉴权

1.4 接口权限说明

鉴权不通过或APPID与当前工作流不匹配，会返回相关流控错误。

2. 请求

2.1 请求协议示例

{
    "flow_id": "7265177322515169282",
    "uid": "123",
    "parameters": {
        "AGENT_USER_INPUT": "你好"
    },
    "ext": {
        "bot_id": "workflow",
        "caller": "workflow"
    },
    "stream": true,
    "chat_id": "xxx",
    "history": [
      { 
        "role": "user", 
        "content_type": "text", 
        "content": "你好" 
      },
      { 
        "role": "assistant", 
        "content_type": "text", 
        "content": "你好,我是你的工作助手，请问有什么可以帮您？" 
      }
    ]
}

2.2 请求参数

2.2.1 Header

2.2.2 Body

history_message Object

在处理 history_message object 时，首个元素的 role 必须为 user。交互历史应按照 user -> assistant -> user -> assistant 的顺序进行拼接，默认情况下，user 与 assistant 之间的一对交互视为一轮对话。按对话时间从先到后依次填充。如[{第一次},{第二次}...]

[
  // 拼接对话历史信息:
  {"role": "user", "content_type" : "text", "content": "湖南有哪些美食"},              // 用户第一个问题   role是user,表示是用户的提问
  {"role": "assistant", "content_type" : "text", "content": "湖南有xxxxxx"},        // AI的第一个回复  role是assistant，表示是AI的回复
]

3. 响应

3.1 响应协议示例

3.1.1 流式结果示例

流式输出过程帧

{
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ]
}

流式输出结束帧

{
  "code": 0,
  "message": "Success", 
  "id": "spf0016609f@dx193193f43cba44d782",
  "created": 123412324431,
  "workflow_step": {
    "seq": 6,
    "progress": 1
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 0,
    "total_tokens": 9
  }
}

3.1.2 非流式结果示例

{
  "code": 0,
  "message": "Success",
  "id": "cha000b0003@dx1905cd86d6bb86d552",
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，我是由科大讯飞构建的星火认知智能模型。\n如果你有任何问题或者需要帮助的地方，请随时告诉我！我会尽力为你提供解答和支持。请问有什么可以帮到你的吗？",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": "stop",
      "finish_reason": ""
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 42,
    "total_tokens": 48
  }
}

3.1.3 中断事件

当工作流中有问答节点时，工作流会被中断

问答节点中断帧（直接回答）

{
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ],
  "event_data": {
        "event_id": "7336690112690499584",
        "event_type": "interrupt",
        "need_reply": true,
        "value": {
            "type": "direct",
            "content": "你想购买以下哪个套餐？"
        }
    }
}

问答节点中断帧（选项回答）

{
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ],
  "event_data": {
        "event_id": "7336690112690499584",
        "event_type": "interrupt",
        "need_reply": false,
        "value": {
            "type": "option",
            "content": "请选择你的套餐",
            "option": [
                {
                    "id": "A",
                    "text": "年度套餐"
                },
                {
                    "id": "B",
                    "text": "月度套餐"
                }
            ]
        }
    }
}

3.1.4 异常结果

{
    "code": 20805,
    "message": "flow id : 7265177322515169282 状态为草稿，请发布",
    "id": "spf00dc0001@hf193621572a96806782",
    "created": 1732517393,
    "choices": [
        {
            "delta": {
                "role": "assistant",
                "content": "",
                        "reasoning_content": ""
            },
            "finish_reason": "stop"
        }
    ],
    "workflow_step": {
        "seq": 0,
        "progress": 1.0
    },
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    }
}

3.2 响应参数

3.2.1 响应数据参数

3.2.2 结果格式补充说明

模型结果除了普通文本类型，为了满足排版需求，会出现以下的标记语言，建议集成方进行适配：

• markdown（表格、列表等）

二、恢复运行工作流

1. 基础信息

1.1 接口说明

1.2 接口Demo

接口Demo随后提供。

1.3 接口要求

接口类型: 流式http(s)

2. 请求

2.1 请求协议示例

{
    "event_id": "123456789012345",
    "event_type": "resume",
    "content": "我的姓名是:xxxx, 年龄：xxxx"
}

2.2 请求参数

2.2.1 Header

2.2.2 Body

3. 响应

3.1 响应协议示例

3.1.1 流式结果示例

流式输出过程帧

{
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ]
}

流式输出结束帧

{
  "code": 0,
  "message": "Success", 
  "id": "spf0016609f@dx193193f43cba44d782",
  "created": 123412324431,
  "workflow_step": {
    "seq": 6,
    "progress": 1
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 0,
    "total_tokens": 9
  }
}

3.1.2 非流式结果示例

{
  "code": 0,
  "message": "Success",
  "id": "cha000b0003@dx1905cd86d6bb86d552",
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，我是由科大讯飞构建的星火认知智能模型。\n如果你有任何问题或者需要帮助的地方，请随时告诉我！我会尽力为你提供解答和支持。请问有什么可以帮到你的吗？",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": "stop",
      "finish_reason": ""
    }
  ],
  "usage": {
    "prompt_tokens": 6,
    "completion_tokens": 42,
    "total_tokens": 48
  }
}

3.1.3 中断事件

当工作流中有问答节点时，工作流会被中断

问答节点中断帧（直接回答）

{
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ],
  "event_data": {
        "event_id": "7336690112690499584",
        "event_type": "interrupt",
        "need_reply": true,
        "value": {
            "type": "direct",
            "content": "你想购买以下哪个套餐？"
        }
    }
}

问答节点中断帧（选项回答）

{
  "code": 0,
  "message": "Success",
  "id": "cha000c0076@dx191c21ce879b8f3532",
  "created": 123412324431,
  "workflow_step": {
    "seq": 0,
    "progress": 0.4
  },
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "content": "你好，",
        "reasoning_content": ""
      },
      "index": 0,
      "finish_reason": null
    }
  ],
  "event_data": {
        "event_id": "7336690112690499584",
        "event_type": "interrupt",
        "need_reply": false,
        "value": {
            "type": "option",
            "content": "请选择你的套餐",
            "option": [
                {
                    "id": "A",
                    "text": "年度套餐"
                },
                {
                    "id": "B",
                    "text": "月度套餐"
                }
            ]
        }
    }
}

3.1.4 异常结果

{
    "code": 20805,
    "message": "flow id : 7265177322515169282 状态为草稿，请发布",
    "id": "spf00dc0001@hf193621572a96806782",
    "created": 1732517393,
    "choices": [
        {
            "delta": {
                "role": "assistant",
                "content": "",
                        "reasoning_content": ""
            },
            "finish_reason": "stop"
        }
    ],
    "workflow_step": {
        "seq": 0,
        "progress": 1.0
    },
    "usage": {
        "prompt_tokens": 0,
        "completion_tokens": 0,
        "total_tokens": 0
    }
}

4.2 响应参数说明

4.2.1 响应数据参数

4.2.2 结果格式补充说明

模型结果除了普通文本类型，为了满足排版需求，会出现以下的标记语言，建议集成方进行适配：

• markdown（表格、列表等）

三、文件上传

1. 基础信息

1.1 接口说明

1.2 接口Demo

curl -X POST 'https://xingchen-api.xf-yun.com/workflow/v1/upload_file' \
--header 'Authorization: Bearer {api_key}' \
--form 'file=@localfile;type=image/[png|jpeg|jpg|webp|gif]

1.3 接口要求

接口类型: 流式http(s)

接口鉴权: Bearer鉴权

2. 请求参数

2.1 Header

2.2 Body

3. 响应

3.1 响应协议示例

{
  "code": 0,
  "message": "success",
  "sid": "spf001b23c7@dx1939b17d9e3a4f3700",
  "data": {
      "url": "xxxxxxxxxx"
  }
}

3.2 响应参数说明

四、错误码列表

1. 工作流错误

2. 模型错误

3. API授权

4. 文生图

5. 工具错误

6. 节点执行错误

7. 会话